fix(objectql): the validation-message bridge negotiates the locale through the one rule every other consumer uses - #16087

Fixes #15757

accept-language: zh was answered with an English refusal on the same response whose dataset, view and object labels were already Chinese. This routes the one path that never negotiated through the negotiation rule every other consumer already runs.

The mechanism

@objectstack/spec has exactly one locale-negotiation rule, resolveBundleLocale (packages/spec/src/system/i18n-resolver.ts:284): exact match, then case-insensitive, then base language, then variant expansion — the step that reaches a zh-CN bundle from a bare zh. pickData calls it, and every document translator (translateObject, translateView, translateDataset, ...) goes through pickData. That is why an app shipping only zh-CN still answered a bare zh with translated labels.

The write path's message bridge did not. ExecutionContext.locale is the header's first tag verbatim — preferredLocaleFromHeader reports what was asked for and expands nothing, deliberately, because each of its callers negotiates differently — and ObjectQL.validationMessageContext handed that tag straight to II18nService.t(). A served adapter resolves a locale exactly and then falls to its declared fallback (FileI18nAdapter.t() is resolveFromLocale(key, locale) then resolveFromLocale(key, fallbackLocale), with no variant step). So zh missed the zh-CN bundle and the English rule.message came back from authoredRuleMessage (packages/objectql/src/validation/rule-validator.ts:2458).

The change

validationMessageContext (packages/objectql/src/engine.ts:6085) now resolves the requested tag against what the bridged service reports it holds (II18nService.getLocales()), through that same resolveBundleLocale.

One seam, four call sites. validationMessageContext is the single producer of messages.locale, consumed at engine.ts:9914, :10353, :11505 and :12942. Fixing the producer fixes both consumers of that value at once — authoredRuleMessage's objects.OBJECT._validations.RULE.message lookup and renderValidationMessage's validation.field.* deployment-override hook, which was passed the un-negotiated tag for the same reason.

The rule is not re-implemented in packages/objectql — that would be a third negotiation rule, which is the disease this card exists to remove. The document translators ask resolveBundleLocale about a bundle's keys; this asks it about the service's locales. One rule, two questions.

The tag passes through untouched whenever there is nothing to negotiate against: no service, no getLocales, an empty / non-array / throwing answer, or a tag no variant of which is on offer.

preferredLocaleFromHeader is untouched, and so is every other caller of it.

The evidence table, rebuilt in-repo

packages/objectql/src/engine-validation-locale-negotiation.test.ts. One bundle feeds both paths — t() addresses it by dot-notation key and the document translator reads the same nested locations out of the same object — so this is a control, not two unrelated readings. The i18n service is shaped after FileI18nAdapter.t() (requested locale exactly, then the declared fallback, then the key echoed back), and each row is driven from the raw header through preferredLocaleFromHeader.

Three of the four rows are controls. zh-CN and zh-CN,zh;q=0.9 prove the path itself works — the key is present, the bundle is loaded; en proves the fallback is right. Only bare zh was the defect.

Cross-path control, same header, same bundle: the document translator returns the Chinese field labels for zh both before and after. Before the fix, the same server, the same bundle and the same header produced opposite answers on the two paths — that is what turned "two negotiation rules" from an inference into a fact.

The table is built as a whole before it is asserted, so all four rows are reported by one run: a row that stops the test is a row whose controls were never read.

Ablation of the pin

One shell, absolute paths, trap ... EXIT INT TERM, against a clean committed tree. The suite resolves the mutated file as source (a relative ./engine import; this package's vitest.config.ts declares no alias), so no rebuild is owed on either leg.

• Mutation proven on disk before measuring — the fixed spelling went 1 → 0 and the reverted spelling 0 → 1 by anchored grep -c -F, and the blob moved 333fce685… → 6adbe9c5a…. A run that cannot prove this exits 90 and voids the reading rather than reporting a green.
• Pin went red: vitest exit 1, Test Files 1 failed (1) / Tests 3 failed | 3 passed (6). The three that failed are exactly the locale-negotiating ones; the three that held are the envelope-invariance, no-match and no-getLocales pins, which is the right split — those three do not measure this fix.
• The failing assertion is a one-row diff, which is the whole card:

  -   "zh": (the Chinese authored message)
  +   "zh": "Say why the duty is being returned - the owner needs to know what to change."
  

  The three control rows did not move. That is what makes them controls.
• Restore proven after: blob back to 333fce685… == HEAD blob, git diff HEAD empty, git status --porcelain empty.

Clause-② — both limbs, measured separately

Instrument: build at head, swap packages/objectql/src/engine.ts back to origin/main, rebuild, diff every declaration file the package publishes — resolved from exports (. and ./core) plus files: ["dist"], which is six files, not one — then restore byte-exact and prove it.

⚠️ The root barrel is not where this lives, and diffing it alone would have understated the result. setI18nService appears in neither dist/index.d.ts nor dist/core.d.ts: it is in the shared chunk dist/util-*.d.ts that both entry points re-export and that ships under files. Both barrels did differ, but only in the content-hashed chunk name they import from (util-D3s8yRSa → util-DwjDS0EK), with byte-identical export lists — a delta that carries no information on its own.

Limb 1 — does any exported symbol or signature move? YES, additively. In the shared chunk, on the exported ObjectQL class:

  setI18nService(service: {
      t?: (key: string, locale: string, params?: Record<string, unknown>) => string;
+     getLocales?: () => string[];
  }): void;

plus private negotiatedMessageLocale;, which is not callable. Nothing exported was removed or renamed and no return type moved; the parameter's accept set strictly widened, so nothing that typechecked before stops typechecking. II18nService has always required getLocales(), so every real service already satisfies it — the member is optional here only because the setter has always accepted a partial shim.

Limb 2 — is any request newly accepted or rejected? NO — measured, not asserted. A pin reads the machine-readable half of the envelope for every header: same code (rule_violation), same field (return_note), refused in every locale including de; and a record that satisfies the rule is still accepted in zh-CN, zh, en and de. Only the sentence's language moves — an answer changing inside an already-refused response, not an accept set moving.

⇒ Clause-② is yes on limb 1. needs:contract-review is on both carriers and the PR stays draft. Note this is the opposite of the dispatching seat's own non-binding prediction (no, "no exported symbol or signature should move"); measurement is what caught it, which is why the round re-derives rather than inherits.

@objectstack/spec is not touched (the three-dot change set against the merge base is four files, none under packages/spec), so no spec-side artifact regeneration or ablation is owed.

Documentation drift

Read at this head; per-page verdict, and no page needed an edit.

• content/docs/ui/translations.mdx — corroborated, and it is the page the code contradicted. Its "How a locale is chosen" section states the rule generally: "matching walks: exact (zh-CN) → case-insensitive → base language (zh-CN → zh) → variant expansion (zh → zh-CN)". The same page's key table lists the custom validation-rule message key as translatable, and its "Honest limits" section describes the write path swapping the whole sentence. So the documented contract already promised variant expansion for this key; the validation-message path was a silent exception to the page's own stated rule. The fix removes the exception. No edit — writing new prose here would be widening.
• content/docs/protocol/kernel/i18n-standard.mdx — untouched. Its "Locale Fallback" section documents only the narrowing direction (de-AT → de, then the declared fallback) and says nothing about variant expansion or about the validation-message path. Silence, not falsehood; and it already links to the translations page for the fuller rule, so the two stay consistent.
• content/docs/api/client-sdk.mdx, content/docs/api/wire-format.mdx, content/docs/protocol/kernel/index.mdx — untouched. Each says only that Accept-Language carries the locale; none makes a claim about how a tag is matched to a bundle.
• content/docs/references/** is generated and content/docs/releases/** is release-owned; neither carries a negotiation claim and neither is edited here.

The only documentation file in this diff is content/docs/permissions/system-context.mdx, and only as line-number anchors, below.

Merge, and the census

This branch merged current origin/main through scripts/pm/os-regen-merge.sh, the sanctioned sequence: the census page is routed to the merge=os-regen driver in .gitattributes, so a text merge of it cannot be right. Both sides had moved it — main re-anchored share-link-service.ts rows, this branch's engine.ts insertion moved fifteen objectql/src/engine.ts anchors — so the script took main's side and the census was regenerated from the merged tree. Verified afterwards that both sides survived: main's share-link-service.ts:459 row and this branch's engine.ts:11733 / :10381 / :14981 anchors are all present. Nothing but line numbers changed — no prose, no row, no behaviour, and nothing under content/docs/releases/.

pnpm check:system-context-census verdict on the result: OK — 105 elevation read sites in 19 packages across 44 files, all anchored; 140 anchors resolve, 27 declared non-read.

Verification

Gate family re-derived after the final commit with node scripts/pm/dispatch-gates.mjs --repo objectstack-ai/objectstack; its provenance line confirms the answer comes from this repo's tree at 2634da48b, over the three-dot change set against merge base 1157e7b72. It names 87 distinct families.

Declared narrowing: 87 families were not run locally — CI runs that farm exactly once, and it has. What was run at 2634da48b, with each exit code captured before any pipe (cmd > log 2>&1; EXIT=$?) and each gate's own verdict line read rather than a bare $?:

• dependency closure built first, then pnpm --filter @objectstack/objectql exec vitest run over the new suite plus rule-validator.test.ts and record-validator.test.ts — Test Files 3 passed (3), Tests 289 passed (289).
• pnpm --filter @objectstack/objectql typecheck — green across all three legs. Worth stating precisely: leg 1 (tsc --noEmit, the build config) does not compile the new test file — --listFiles puts engine.ts in the program and the test file at 0 hits, because that config excludes tests deliberately. The leg that covers it is check:test-typecheck against tsconfig.test.json, whose verdict is OK — @objectstack/objectql's test layer compiles ... 44 file(s) / 242 error(s) / 69 pinned signature(s) held, unchanged. So "typecheck is green" is a claim about the test file only via that third leg.
• 18 targeted gates, the ones this diff actually implicates, all exit 0: nul-bytes, engine-double-contract, objectql-double-limit, where-matcher, test-source-alias, cross-package-test-inputs, system-context-census, merge-driver, type-check-coverage, durability-log-level, swallow-census-controls, stack-collection-maps, changeset-gate-self-tests, objectui-changeset, doc-anchors, docs-single-h1, corpus-claim-drift, adr-0087-registration.

Heavy steps ran through scripts/pm/os-verify-lock.sh; every wall-clock figure it printed is a shared-box reading, not an idle-box one.

Out of scope, filed separately

packages/core/src/fallbacks/memory-i18n.ts:47 exports resolveLocale(requestedLocale, availableLocales[]) — a behaviourally identical second copy of resolveBundleLocale (same four steps, same order), list-shaped instead of record-shaped. It produces the same answers, so it is a maintenance hazard rather than a live defect, and collapsing it is a different package and a different change. Filed as #16085.

Generated by Claude Code